Azure Pipelines

Pipeline yaml 復盤

請參考範例程式，今天要說明的兩個pipeline yaml都在這資料夾下：
ironman2025\case_ELK_JPG_Route_HMAC\pipelines\

.
├── pipelines/
│    ├─── tmp_kong.yaml       #共用步驟範本
│    ├─── SIT_Kong_sync.yaml  #SIT 環境各參數
│    ├─── UAT_Kong_sync.yaml  #尚未建立
│    └─── Prod_Kong_sync.yaml #尚未建立

今天讓筆者來說明，昨天執行的那個pipeline到底在幹甚麼。上面可以看到是昨天執行pipeline的目錄結構，下面的UAT_Kong_sync.yaml以及Prod_Kong_sync.yaml是會發現找不到，那是筆者刻意放在上面做為示範使用。

首先先說明檔案目的，筆者有一個習慣，當有一個行為在不同環境中重複時，會撰寫共用的範本yaml檔案，這邊的例子就是temp_kong.yaml。這種做法的優點是，在不同環境中所有動作，都會是一致執行步驟。

圖22-1 pipeline 中的範本與引用

可以參考圖22-1，筆者會養成這樣的習慣是因為，過去曾經發生過，在不同環境因為參數的調整，調整了dev環境卻忘了prod環境要一起處理。因此後來就養成了撰寫範本檔的習慣，一方面每一個步驟都抽到範本檔執行，而不同環境各自要帶入的參數，則是透過環境檔進行傳入執行。例如這次要講解的範例，就用SIT_Kong_sync.yaml做為示範。

trigger:
  branches:
    include:
      - main
  paths:
    include:
      - SIT/Kong_declarative/declarative/kong.yml

stages:
  - template: tmp_kong.yaml
    parameters:
      environmentName: 'Demo SIT'
      docker_compose_path: 'C:/Users/samnc/2025_ironman/ironman2025/case_ELK_JPG_Route_HMAC'
      kongDeployConfigPath: '1.Kong_declarative/declarative'
      kongConfigPath: 'SIT/Kong_declarative/declarative'      

程式碼範例 SIT_Kong_sync.yaml

首先先說明環境準備檔，筆者用列點的方式簡單說明：

• trigger區段：
  • 監控git的main分支，以及指定路徑下的kong.yml檔案。
  • 上述兩個條件共同成立時，觸發這個pipeline。
• stages區段：
  • 呼叫範本檔tmp_kong.yaml：
    • 傳入各項參數，包含：
    • environmentName執行環境的名稱，這邊執行環境是day 22建立environment時所取的名字。
    • docker compose所在的路徑、kong config希望被佈署到的目錄，git repo中kong.yml的所在位置。

這樣設計是不是就實踐了，可以讓多個環境（如 SIT、UAT、Prod）共用相同的部署步驟，只需根據環境傳入不同參數，確保流程一致且易於維護。

觸發條件則是根據 main 分支的指定資料夾路徑（kong.yml）有變更時，自動觸發 pipeline。這樣就能夠做到不同資料夾代表的是不同的環境，進而讓檔案能夠完整敘述該環境kong 的的狀態。

程式碼範例 tmp_kong.yaml

parameters:
  - name: environmentName
    type: string
  ...省略部分參數引入...

stages:
  - stage: 'SettingKong'
    displayName: 'Setting_Kong'
    jobs:
      - deployment: 'KongSetting'
        displayName: 'Kong Setting for ${{ parameters.environmentName }}'
        workspace:
          clean: all
        environment:
          name: ${{ parameters.environmentName }}
          resourceType: VirtualMachine
        strategy:
          runOnce:
            deploy:
              steps:
                - checkout: self
                  clean: true
                - task: PowerShell@2
                  displayName: '將原有kong.yml備份'
                  inputs:
                    targetType: 'inline'
                    script: |
                      cd ${{ parameters.docker_compose_path }}/${{ parameters.kongDeployConfigPath }}
                      cp kong.yml kong.yml.bak
                      cp $(System.DefaultWorkingDirectory)/${{ parameters.kongConfigPath }}/kong.yml ./kong.yml
                - task: PowerShell@2
                  displayName: ' 重新啟動Kong'
                  inputs:
                    targetType: 'inline'
                    script: |
                      cd ${{ parameters.docker_compose_path }}
                      pwd
                      docker compose restart kong-dbless

                      # 檢查 kong-dbless 是否有啟動
                      $container = docker ps --filter "name=kong-dbless" --filter "status=running" --format "{{.Names}}"
                      if (-not $container) {
                        Write-Error "kong-dbless 未啟動，請確認 docker compose up 是否已經執行過。"
                        exit 1
                      } else {
                        Write-Host "kong-dbless 已啟動。"
                      }

同樣的，這邊筆者也用列點的方式說明tmp_kong.yaml這個檔案執行步驟。

• 參數引入區段
  • 檔案最上方定義了多個參數輸入（如 environmentName、docker_compose_path...），方便不同環境重複利用這個範本。
• Stage：SettingKong
  • 這個 stage 會在指定的 Azure DevOps Environment上執行，這次是用筆者的電腦做為執行環境示範。
  • 主要步驟
    • checkout：將 repo 內容拉到 agent。
    • 備份與覆蓋 kong.yml：先備份原有的 kong.yml，再用 repo 中最新的 kong.yml 覆蓋。
    • 重啟 Kong 服務：進入 docker compose 目錄，執行 docker compose restart kong-dbless，讓 Kong 載入新設定。
    • 檢查 Kong 是否啟動：用 docker ps 檢查 kong-dbless 是否有成功啟動，若沒啟動則 pipeline 失敗。

這完成了甚麼？

上面那些pipeline到底完成了甚麼？其實就是做到了變更管理的所有軌跡與設定狀態留存。相信讀者一定有經驗，就是在某個UI的軟體或是平台上，曾經調整過了甚麼，但過了可能幾步之後，就甚麼都忘記了。

而IaC的真義，有很大一部分就是希望可以將所有曾經變更過相關設定的軌跡，都跟程式碼的變更一樣被git以變更記錄歷史的方式被保留下來。

接下來就來實驗看看，到底甚麼行為會觸發這個pipelines。

變更管理的實驗

- acls:
  - group: trial
  username: user2@user.com
  custom_id: user2
  keyauth_credentials:
  - key: user2-api-key

目前筆者已經將自己電腦中的docker compose啟動完成了，接下來先鎖定一個準備要來進行變更設定檔。請參考上方程式碼範例，這是kong.yml檔案中，關於user2@usr.com的apikey設定。

圖22-2 正確的請求與回應

另外筆者也用上述的設定，來對api進行請求，確認無誤，請參考圖22-2。可以發現攜帶apikey=user2-api-key可以獲得正確的回應，這表示這段設定還是生效的。

接下來就要進行變更管理了，場景就假設是，雙方約定每年需要進行apikey的輪替，這時候，就需要將Azure repos中的設定檔，將apikey進行替換。

筆者使用VSCode進行將kong.yml變更(圖22-3)，並將變更後的設定檔進行git commit and push。

圖22-3 變更後的apikey

這時候，就會注意到昨天被設定好的azure pipeline因為main分支的kong.yml被變更了。因此這條流水線就被成功觸發，而且也順利執行完畢，可以參考圖22-4。

圖22-4 被觸發與執行成功的流水線

接下來就是實驗的時候，來確認變更是否成功，一樣使用postman來做驗證，可以發現剛剛還可以成功請求的api，已經被回饋401的錯誤了(圖22-5)。

圖22-5 原有api-key已無法登入

這表示至少原本的api-key已經無法使用，那當然要來驗證變更後的api-key是不是能正常使用。

圖22-6 新的api-key已經生效可使用

從圖22-6已經可以確認，這次變更管理已經生效了。接下來到Azure DevOps中確認一下這次變更的軌跡。

圖22-7 點選pipeline 旁的SHA

圖22-8 變更管理的軌跡

從圖22-7 到圖22-8就可以看出來，這次變更管理的完整軌跡就被保留在Azure Repo中，變更的目的也因為commit時有將相關資訊留下，因此可以判斷這次變更內容當下的目的。

小結

這樣就完成了一個最簡單的IaC變更管理了....嗎？其實不只是這樣，實際上在DevOps的領域中，變更管理除了可回溯以外，其實還有一個非常重要的議題，那就是與團隊共同討論與審查。

目前這樣的作法，僅有將變更軌跡留下，並根據自動化流水線執行變更。這樣是不是對於Infrastructrue的人來說，有一點慢又有一點麻煩呢？

筆者應該可以注意到，其實這一個變更需要大概一分鐘的時間才能夠完成。這就要注意到可能發生一件事情，例如這一個變更發生問題當下，如果因為異常狀況而需要做再次變更，要先將設定檔調整完畢後，推上Azure Repo觸發，又要等大約一分鐘才可以完成緊急異常作業。

這是不是有點....讓人稍微卻步？因為過往Infrastructrue的同仁例如調整防火牆異常，馬上異動設定就可以變回原本的樣子。特別是筆者觀察過許多基礎設施的技術人員友，他們非常習慣用xxx.20250914.back將設定檔備份在旁邊，一出問題馬上就可以匯入，應該不用一分鐘就可以完成。

為了這個議題，筆者還有幾個小妙招與方法，盡可能的增加變更成功的機率，並減少還原的時間。

明天就讓我們一起來探討要如何完成~